# 内部研发文档

```{admonition} 本文引用的文件
:class: note

- `升级到micropython_v1.23.0.md`
- `new_board-labplus_Ledong_pro.md`
- `project_add_esp_adf.md`
- `usb-otg and usb-serial-jtag.md`
- `CMakeLists.txt`
- `mpython_v3/mpconfigboard.cmake`
- `labplus_Ledong_v2/mpconfigboard.cmake`
- `mpython_v3/mpconfigboard.h`
- `labplus_Ledong_v2/mpconfigboard.h`
- `mpython_v3/sdkconfig.usb`
- `labplus_Ledong_v2/sdkconfig.usb`
```

## 产品概述
本技术文档面向内部研发团队，聚焦以下主题：
- MicroPython版本迁移（从旧版到v1.23.0及ESP-IDF v5.x）
- 新板型适配流程与要点（以乐动掌控系列为例）
- ESP-ADF音频框架集成与裁剪策略
- USB OTG与USB Serial/JTAG在S3板上的启用与配置

项目基于MicroPython for ESP32/ESP32-S3定制，采用ESP-IDF CMake构建系统，按板型隔离配置与模块，便于多产品线并行开发与发布。

## 核心业务流程
- 版本迁移流程：引入新版Micropython与ESP-IDF，调整构建脚本、组件路径、QSTR与模块注册，确保各板型可编译并功能可用。
- 新板型适配流程：复制基础模板，完成引脚、I2C、PSRAM、分区表、manifest冻结、builtin模块与Python库的板级配置，验证REPL/USB/显示/音频等关键能力。
- ESP-ADF集成流程：按需拷贝组件、裁剪依赖、合并sdkconfig，控制固件体积，提供录音/播放/语音识别/合成等能力。
- USB OTG/Serial JTAG流程：通过sdkconfig启用TinyUSB CDC与JTAG Console，结合板级配置实现自动下载与调试。

```text
flowchart TD
A["开始"] --> B["选择目标板型<br/>mpython_v3 / labplus_Ledong_v2"]
B --> C{"是否新增板型?"}
C -- 是 --> D["新建板目录与配置<br/>mpconfigboard.* / sdkconfig.*"]
C -- 否 --> E["复用现有板配置"]
D --> F["添加builtin与Python模块<br/>manifest冻结"]
E --> F
F --> G{"是否需要ESP-ADF?"}
G -- 是 --> H["拷贝并裁剪组件<br/>audio_stream/esp-sr/..."]
G -- 否 --> I["跳过ADF集成"]
H --> J["合并sdkconfig并构建"]
I --> J
J --> K{"是否启用USB OTG/JTAG?"}
K -- 是 --> L["启用CONFIG_USB_OTG_SUPPORTED<br/>CONFIG_TINYUSB_CDC_ENABLED<br/>CONFIG_ESP_CONSOLE_USB_SERIAL_JTAG"]
K -- 否 --> M["保持默认串口控制台"]
L --> N["构建/烧录/联调"]
M --> N
N --> O["结束"]
```

**章节来源**
- `升级到micropython_v1.23.0.md:23-94`
- `new_board-labplus_Ledong_pro.md:1-43`
- `project_add_esp_adf.md:1-12`
- `usb-otg and usb-serial-jtag.md:1-5`

## 功能模块清单
- 构建系统与板级配置
  - 顶层CMakeLists负责解析MICROPY_BOARD、包含板级mpconfigboard.cmake、合并sdkconfig、生成合并配置文件并调用idf_build_set_property与project(micropython)。
  - 板级mpconfigboard.cmake定义IDF_TARGET、SDKCONFIG_DEFAULTS、MICROPY_SOURCE_BOARD与MICROPY_SOURCE_BOARD_DIR、冻结manifest路径，并可开启板级宏开关。
- 板型差异与外设
  - mpython_v3与labplus_Ledong_v2均启用音乐、音频、RFID与新I2C驱动；I2C引脚不同；USB Serial/JTAG与OTG支持通过sdkconfig.usb启用。
- 模块冻结与内置C模块
  - 通过manifest.py将常用Python模块冻结入ROM，减少内存占用并提升启动速度；builtin层包含machine_pin、touchpad、framebuf、i2c、timer、music、nvs、network_wlan等。
- ESP-ADF音频能力
  - 通过拷贝必要组件并按需裁剪，提供录音、播放、TTS/IAT等能力；注意去除冗余依赖以降低固件体积。
- USB OTG与调试
  - 启用TinyUSB CDC与JTAG Console，配合bootloader与工具链实现自动下载与调试；缓冲区大小可按需调整。

**章节来源**
- `CMakeLists.txt:12-66`
- `mpython_v3/mpconfigboard.cmake:1-44`
- `labplus_Ledong_v2/mpconfigboard.cmake:1-50`
- `mpython_v3/mpconfigboard.h:1-29`
- `labplus_Ledong_v2/mpconfigboard.h:1-29`
- `mpython_v3/sdkconfig.usb:1-9`
- `labplus_Ledong_v2/sdkconfig.usb:1-8`

## 数据与状态
- 构建产物与配置
  - 顶层CMake生成sdkconfig.combined.in并输出为sdkconfig.combined供ESP-IDF使用；锁定文件用于检测依赖变更。
- 板级状态标志
  - 通过MPY_PORT_DIR、MICROPY_BOARD、MICROPY_BOARD_VARIANT、MPYTHON_V3_BOARD/LABPLUS_LEDONG_V2_BOARD等宏区分板型与变体，影响源文件集合与组件目录。
- 运行时模块状态
  - 冻结manifest决定哪些Python模块被预编译并驻留ROM；builtin C模块初始化顺序影响I2C、TouchPad、Pin、Timer、Music、NVS、WiFi等子系统可用性。
- 音频与USB状态
  - ESP-ADF组件加载后，音频流、编解码器、网络服务处于待命或运行态；USB OTG/CDC启用后，控制台与虚拟串口就绪。

```text
graph TB
subgraph "构建期"
T["顶层CMakeLists.txt"] --> B["板级mpconfigboard.cmake"]
B --> S["合并sdkconfig.combined"]
S --> IDF["ESP-IDF构建"]
end
subgraph "运行期"
ROM["冻结Python模块(ROM)"] --> APP["用户应用"]
BUILTIN["Builtin C模块"] --> APP
ADF["ESP-ADF组件"] --> APP
USB["USB OTG/CDC/JTAG"] --> APP
end
IDF --> ROM
IDF --> BUILTIN
IDF --> ADF
IDF --> USB
```

**图表来源**
- `CMakeLists.txt:32-66`
- `mpython_v3/mpconfigboard.cmake:19-44`
- `labplus_Ledong_v2/mpconfigboard.cmake:19-50`

**章节来源**
- `CMakeLists.txt:32-66`
- `mpython_v3/mpconfigboard.cmake:19-44`
- `labplus_Ledong_v2/mpconfigboard.cmake:19-50`

## 关键约束与边界
- 版本与依赖边界
  - 升级至Micropython v1.23.0与ESP-IDF v5.0.4时，需遵循新的CMake与组件管理方式；qstr、模块注册、GC指针管理等细节需对齐新版本。
- 板型边界
  - 每块板独立维护mpconfigboard.*与sdkconfig.*；I2C引脚、PSRAM类型与容量、分区表布局必须与硬件一致；manifest冻结需按板型裁剪。
- ESP-ADF边界
  - 仅拷贝必要组件并按需裁剪CMake依赖，避免引入冗余代码导致固件过大；tone_partition与wifi_service等组件需显式处理依赖关系。
- USB OTG/Serial JTAG边界
  - 启用USB OTG与CDC需保证引脚与电源设计满足要求；JTAG Console需与bootloader协同，确保自动下载与调试链路畅通。
- 性能与体积
  - 冻结模块可减少RAM占用并加速启动；精简ADF组件与禁用未用功能有助于降低Flash占用与功耗。

**章节来源**
- `升级到micropython_v1.23.0.md:23-94`
- `new_board-labplus_Ledong_pro.md:1-43`
- `project_add_esp_adf.md:1-12`
- `usb-otg and usb-serial-jtag.md:1-5`
- `mpython_v3/sdkconfig.usb:1-9`
- `labplus_Ledong_v2/sdkconfig.usb:1-8`